It does not fit with functions ntohl, htonl, ntohs, htons, described in previous paragraph, which only work with 16 and 32 bit integers.

Yes, but I'm not sure it has to, since those two paragraphs are describing separate topics, and the respective integer widths are each appropriate to the point being made—the standard library functions are nominally for smaller 16 and 32-bit integers, while modern machines and Python's own native integer type are 64-bit, where encoding small integers as ASCII/UTF-8 has the greatest potential size advantage over binary, while also avoiding the need to potentially convert endianness, particularly so when the aforementioned functions are not available for 64-bit ints (though perhaps one could be added).

Is there something specific you'd like me to add/clarify here?

It is obvious to me that this paragraph refers to the previous one. It's mention of "all those longs" is a reference to "long" in ntohl and htonl which is always 32-bit.

Also, on most modern 64-bit platforms the standard integer type int in C is 32-bit. On Windows even long is 32-bit.

It is obvious to me that this paragraph refers to the previous one. It's mention of "all those longs" is a reference to "long" in ntohl and htonl which is always 32-bit.

Okay, thanks for providing something specific. I replaced that wording with "most integers", as well as clarified the terminology in the following sentence as well. If there's something else specific you would like me to change, let me know.

Also, on most modern 64-bit platforms the standard integer type int in C is 32-bit. On Windows even long is 32-bit.

Yes, if by "standard" you mean the C type that has the name int. Of course, this is less relevant for Python users, given Python only has one native integer type, nominally 64 bits, and this how-to does not focus on the C API. In any case, the use of a native 64-bit integer is appropriate to making the point of the section, that with wider binary types, representing small numbers as text may actually be more efficient.

Python 3 does not have a native fixed-width integer type. There was one in Python 2, but it was 32-bit on Windows.

Well, I think it is not important.

Python 3 does not have a native fixed-width integer type. There was one in Python 2, but it was 32-bit on Windows.

Sorry, I should have used clearer terminology—what I meant to imply was "native" to the language vs. third party (e.g. Numpy dtypes), but in this context "native" more conventionally means platform-native, as you say above. I also somewhat inaccurately simplified Python's int type to be a fixed-width 64-bit integer, when that's not truly the case.

Is it what returned on the AMD processors? On my computer it is 'x86_64'.

Update also the docstring of platform.machine().

The original 'proper' name of what is also called the "x86-64" architecture is AMD64, as it was created by AMD and later adopted by Intel when Intel's IA-64 (Itanium) architecture failed in the market. What is returned depends (AFAIK) on the OS, not the CPU; Windows and many (most?) Linux distros call it AMD64 internally, while Apple and some others call it x86-64. Running a freshly built from main Python, as well as 3.9 and 3.10 release builds, platform.machine() returns AMD64 on my Windows system with a stock Intel i7-3730.

Update also the docstring of platform.machine().

I can, but as this PR currently only modifies the docs, I'd rather do that separately; there are other places in the codebase that should be updated too, for consistency.

Docstrings are a part of the docs. If we do not update them together with the rst files, they are left desynchronized.

This only affects the choice of one specific example, both of which are equally accurate and valid, and which will be synchronized if and when I do a similar pass through the codebase itself. Several of the other platform functions, e.g. system(), have differing examples on each. And given the rest of this PR scrupulously avoids touching the code, adding this one trivial change has non-trivial cost, of triggering and requiring a whole suite of extra builds/CIs, and increasing risk for backporting.

Given the change was minor and not strictly required in the first place, and I almost didn't make it, if this is going to be a big issue I'll just drop this change instead, since its not at all worth the cost.

Either way the docstrings and the documentation should be consistent.

Python 3 does not have a native fixed-width integer type. There was one in Python 2, but it was 32-bit on Windows.

Well, I think it is not important.

Either way the docstrings and the documentation should be consistent.